home *** CD-ROM | disk | FTP | other *** search
/ Languguage OS 2 / Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO / gnu / elispman.lha / elispman / sequences.texi < prev    next >
Lisp/Scheme  |  1993-05-19  |  14KB  |  482 lines

  1. @c -*-texinfo-*-
  2. @c This is part of the GNU Emacs Lisp Reference Manual.
  3. @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. 
  4. @c See the file elisp.texi for copying conditions.
  5. @setfilename ../info/sequences
  6. @node Sequences Arrays Vectors, Symbols, Lists, Top
  7. @chapter Sequences, Arrays, and Vectors
  8. @cindex sequence
  9.  
  10.   Recall that the @dfn{sequence} type is the union of three other Lisp
  11. types: lists, vectors, and strings.  In other words, any list is a
  12. sequence, any vector is a sequence, and any string is a sequence.  The
  13. common property that all sequences have is that each is an ordered
  14. collection of elements.
  15.  
  16.   An @dfn{array} is a single primitive object directly containing all
  17. its elements.  Therefore, all the elements are accessible in constant
  18. time.  The length of an existing array cannot be changed.  Both strings
  19. and vectors are arrays.  A list is a sequence of elements, but it is not
  20. a single primitive object; it is made of cons cells, one cell per
  21. element.  Therefore, elements farther from the beginning of the list
  22. take longer to access, but it is possible to add elements to the list or
  23. remove elements.  The elements of vectors and lists may be any Lisp
  24. objects.  The elements of strings are all characters.
  25.  
  26.   The following diagram shows the relationship between these types:
  27.  
  28. @example
  29. @group
  30.             ___________________________________
  31.            |                                   |
  32.            |          Sequence                 |
  33.            |  ______   ______________________  |
  34.            | |      | |                      | |
  35.            | | List | |         Array        | |
  36.            | |      | |  ________   _______  | |   
  37.            | |______| | |        | |       | | |
  38.            |          | | String | | Vector| | |
  39.            |          | |________| |_______| | |
  40.            |          |______________________| |
  41.            |___________________________________|
  42.  
  43. @center @r{The Relationship between Sequences, Arrays, and Vectors}
  44. @end group
  45. @end example
  46.  
  47. @menu
  48. * Sequence Functions::    Functions that accept any kind of sequence.
  49. * Arrays::                Characteristics of arrays in Emacs Lisp.
  50. * Array Functions::       Functions specifically for arrays.
  51. * Vectors::               Functions specifically for vectors.
  52. @end menu
  53.  
  54. @node Sequence Functions, Arrays, Sequences Arrays Vectors, Sequences Arrays Vectors
  55. @section Sequences
  56.  
  57.   In Emacs Lisp, a @dfn{sequence} is either a list, a vector or a
  58. string.  The common property that all sequences have is that each is an
  59. ordered collection of elements.  This section describes functions that
  60. accept any kind of sequence.
  61.  
  62. @defun sequencep object
  63. Returns @code{t} if @var{object} is a list, vector, or
  64. string, @code{nil} otherwise.
  65. @end defun
  66.  
  67. @defun copy-sequence sequence
  68. @cindex copying sequences
  69. Returns a copy of @var{sequence}.  The copy is the same type of object
  70. as the original sequence, and it has the same elements in the same order.
  71.  
  72. Storing a new element into the copy does not affect the original
  73. @var{sequence}, and vice versa.  However, the elements of the new
  74. sequence are not copies; they are identical (@code{eq}) to the elements
  75. of the original.  Therefore, changes made within these elements, as
  76. found via the copied sequence, are also visible in the original
  77. sequence.
  78.  
  79. If the sequence is a string with text properties, the property list in
  80. the copy is itself a copy, not shared with the original's property
  81. list.  However, the actual values of the properties are shared.
  82. @xref{Text Properties}.
  83.  
  84. See also @code{append} in @ref{Building Lists}, @code{concat} in
  85. @ref{Creating Strings}, and @code{vconcat} in @ref{Vectors}, for others
  86. ways to copy sequences.
  87.  
  88. @example
  89. @group
  90. (setq bar '(1 2))
  91.      @result{} (1 2)
  92. @end group
  93. @group
  94. (setq x (vector 'foo bar))
  95.      @result{} [foo (1 2)]
  96. @end group
  97. @group
  98. (setq y (copy-sequence x))
  99.      @result{} [foo (1 2)]
  100. @end group
  101.  
  102. @group
  103. (eq x y)
  104.      @result{} nil
  105. @end group
  106. @group
  107. (equal x y)
  108.      @result{} t
  109. @end group
  110. @group
  111. (eq (elt x 1) (elt y 1))
  112.      @result{} t
  113. @end group
  114.  
  115. @group
  116. ;; @r{Replacing an element of one sequence.}
  117. (aset x 0 'quux)
  118. x @result{} [quux (1 2)]
  119. y @result{} [foo (1 2)]
  120. @end group
  121.  
  122. @group
  123. ;; @r{Modifying the inside of a shared element.}
  124. (setcar (aref x 1) 69)
  125. x @result{} [quux (69 2)]
  126. y @result{} [foo (69 2)]
  127. @end group
  128. @end example
  129. @end defun
  130.  
  131. @defun length sequence
  132. @cindex string length
  133. @cindex list length
  134. @cindex vector length
  135. @cindex sequence length
  136. Returns the number of elements in @var{sequence}.  If @var{sequence} is
  137. a cons cell that is not a list (because the final @sc{cdr} is not
  138. @code{nil}), a @code{wrong-type-argument} error is signaled.
  139.  
  140. @example
  141. @group
  142. (length '(1 2 3))
  143.     @result{} 3
  144. @end group
  145. @group
  146. (length ())
  147.     @result{} 0
  148. @end group
  149. @group
  150. (length "foobar")
  151.     @result{} 6
  152. @end group
  153. @group
  154. (length [1 2 3])
  155.     @result{} 3
  156. @end group
  157. @end example
  158. @end defun
  159.  
  160. @defun elt sequence index
  161. @cindex elements of sequences
  162. This function returns the element of @var{sequence} indexed by
  163. @var{index}.  Legitimate values of @var{index} are integers ranging from
  164. 0 up to one less than the length of @var{sequence}.  If @var{sequence}
  165. is a list, then out-of-range values of index return @code{nil};
  166. otherwise, they produce an @code{args-out-of-range} error.
  167.  
  168. @example
  169. @group
  170. (elt [1 2 3 4] 2)
  171.      @result{} 3
  172. @end group
  173. @group
  174. (elt '(1 2 3 4) 2)
  175.      @result{} 3
  176. @end group
  177. @group
  178. (char-to-string (elt "1234" 2))
  179.      @result{} "3"
  180. @end group
  181. @group
  182. (elt [1 2 3 4] 4)
  183.      @error{}Args out of range: [1 2 3 4], 4
  184. @end group
  185. @group
  186. (elt [1 2 3 4] -1)
  187.      @error{}Args out of range: [1 2 3 4], -1
  188. @end group
  189. @end example
  190.  
  191. This function duplicates @code{aref} (@pxref{Array Functions}) and
  192. @code{nth} (@pxref{List Elements}), except that it works for any kind of
  193. sequence.
  194. @end defun
  195.  
  196. @node Arrays, Array Functions, Sequence Functions, Sequences Arrays Vectors
  197. @section Arrays
  198. @cindex array
  199.  
  200.   An @dfn{array} object refers directly to a number of other Lisp
  201. objects, called the elements of the array.  Any element of an array may
  202. be accessed in constant time.  In contrast, an element of a list
  203. requires access time that is proportional to the position of the element
  204. in the list.
  205.  
  206.   When you create an array, you must specify how many elements it has.
  207. The amount of space allocated depends on the number of elements.
  208. Therefore, it is impossible to change the size of an array once it is
  209. created.  You cannot add or remove elements.  However, you can replace
  210. an element with a different value.
  211.  
  212.   Emacs defines two types of array, both of which are one-dimensional:
  213. @dfn{strings} and @dfn{vectors}.  A vector is a general array; its
  214. elements can be any Lisp objects.  A string is a specialized array; its
  215. elements must be characters (i.e., integers between 0 and 255).  Each
  216. type of array has its own read syntax.  @xref{String Type}, and
  217. @ref{Vector Type}.
  218.  
  219.   Both kinds of arrays share these characteristics:
  220.  
  221. @itemize @bullet
  222. @item
  223. The first element of an array has index zero, the second element has
  224. index 1, and so on.  This is called @dfn{zero-origin} indexing.  For
  225. example, an array of four elements has indices 0, 1, 2, @w{and 3}.
  226.  
  227. @item
  228. The elements of an array may be referenced or changed with the functions
  229. @code{aref} and @code{aset}, respectively (@pxref{Array Functions}).
  230. @end itemize
  231.  
  232.   In principle, if you wish to have an array of characters, you could use
  233. either a string or a vector.  In practice, we always choose strings for
  234. such applications, for four reasons:
  235.  
  236. @itemize @bullet
  237. @item
  238. They occupy one-fourth the space of a vector of the same elements.
  239.  
  240. @item
  241. Strings are printed in a way that shows the contents more clearly
  242. as characters.
  243.  
  244. @item
  245. Strings can hold text properties.  @xref{Text Properties}.
  246.  
  247. @item
  248. Many of the specialized editing and I/O facilities of Emacs accept only
  249. strings.  For example, you cannot insert a vector of characters into a
  250. buffer the way you can insert a string.  @xref{Strings and Characters}.
  251. @end itemize
  252.  
  253. @node Array Functions, Vectors, Arrays, Sequences Arrays Vectors
  254. @section Functions that Operate on Arrays
  255.  
  256.   In this section, we describe the functions that accept both strings
  257. and vectors.
  258.  
  259. @defun arrayp object
  260. This function returns @code{t} if @var{object} is an array (i.e., either a
  261. vector or a string).
  262.  
  263. @example
  264. @group
  265. (arrayp [a])
  266. @result{} t
  267. (arrayp "asdf")
  268. @result{} t
  269. @end group
  270. @end example
  271. @end defun
  272.  
  273. @defun aref array index
  274. @cindex array elements
  275. This function returns the @var{index}th element of @var{array}.  The
  276. first element is at index zero.
  277.  
  278. @example
  279. @group
  280. (setq primes [2 3 5 7 11 13])
  281.      @result{} [2 3 5 7 11 13]
  282. (aref primes 4)
  283.      @result{} 11
  284. (elt primes 4)
  285.      @result{} 11
  286. @end group
  287.  
  288. @group
  289. (aref "abcdefg" 1)
  290.      @result{} 98           ; @r{@samp{b} is @sc{ASCII} code 98.}
  291. @end group
  292. @end example
  293.  
  294. See also the function @code{elt}, in @ref{Sequence Functions}.
  295. @end defun
  296.  
  297. @defun aset array index object
  298. This function sets the @var{index}th element of @var{array} to be
  299. @var{object}.  It returns @var{object}.
  300.  
  301. @example
  302. @group
  303. (setq w [foo bar baz])
  304.      @result{} [foo bar baz]
  305. (aset w 0 'fu)
  306.      @result{} fu
  307. w
  308.      @result{} [fu bar baz]
  309. @end group
  310.  
  311. @group
  312. (setq x "asdfasfd")
  313.      @result{} "asdfasfd"
  314. (aset x 3 ?Z)
  315.      @result{} 90
  316. x
  317.      @result{} "asdZasfd"
  318. @end group
  319. @end example
  320.  
  321. If @var{array} is a string and @var{object} is not a character, a
  322. @code{wrong-type-argument} error results.
  323. @end defun
  324.  
  325. @defun fillarray array object
  326. This function fills the array @var{array} with pointers to @var{object},
  327. replacing any previous values.  It returns @var{array}.
  328.  
  329. @example
  330. @group
  331. (setq a [a b c d e f g])
  332.      @result{} [a b c d e f g]
  333. (fillarray a 0)
  334.      @result{} [0 0 0 0 0 0 0]
  335. a
  336.      @result{} [0 0 0 0 0 0 0]
  337. @end group
  338. @group
  339. (setq s "When in the course")
  340.      @result{} "When in the course"
  341. (fillarray s ?-)
  342.      @result{} "------------------"
  343. @end group
  344. @end example
  345.  
  346. If @var{array} is a string and @var{object} is not a character, a
  347. @code{wrong-type-argument} error results.
  348. @end defun
  349.  
  350. The general sequence functions @code{copy-sequence} and @code{length}
  351. are often useful for objects known to be arrays.  @xref{Sequence Functions}.
  352.  
  353. @node Vectors,  , Array Functions, Sequences Arrays Vectors
  354. @section Vectors
  355. @cindex vector
  356.  
  357.   Arrays in Lisp, like arrays in most languages, are blocks of memory
  358. whose elements can be accessed in constant time.  A @dfn{vector} is a
  359. general-purpose array; its elements can be any Lisp objects.  (The other
  360. kind of array provided in Emacs Lisp is the @dfn{string}, whose elements
  361. must be characters.)  The main uses of vectors in Emacs are as syntax
  362. tables (vectors of integers) and keymaps (vectors of commands).  They
  363. are also used internally as part of the representation of a
  364. byte-compiled function; if you print such a function, you will see a
  365. vector in it.
  366.  
  367.   The indices of the elements of a vector are numbered starting with
  368. zero in Emacs Lisp.
  369.  
  370.   Vectors are printed with square brackets surrounding the elements
  371. in their order.  Thus, a vector containing the symbols @code{a},
  372. @code{b} and @code{c} is printed as @code{[a b c]}.  You can write
  373. vectors in the same way in Lisp input.
  374.  
  375.   A vector, like a string or a number, is considered a constant for
  376. evaluation: the result of evaluating it is the same vector.  The
  377. elements of the vector are not evaluated.  @xref{Self-Evaluating Forms}.
  378.  
  379.   Here are examples of these principles:
  380.  
  381. @example
  382. @group
  383. (setq avector [1 two '(three) "four" [five]])
  384.      @result{} [1 two (quote (three)) "four" [five]]
  385. (eval avector)
  386.      @result{} [1 two (quote (three)) "four" [five]]
  387. (eq avector (eval avector))
  388.      @result{} t
  389. @end group
  390. @end example
  391.  
  392.   Here are some functions that relate to vectors:
  393.  
  394. @defun vectorp object
  395. This function returns @code{t} if @var{object} is a vector.
  396.  
  397. @example
  398. @group
  399. (vectorp [a])
  400.      @result{} t
  401. (vectorp "asdf")
  402.      @result{} nil
  403. @end group
  404. @end example
  405. @end defun
  406.  
  407. @defun vector &rest objects
  408. This function creates and returns a vector whose elements are the
  409. arguments, @var{objects}.
  410.  
  411. @example
  412. @group
  413. (vector 'foo 23 [bar baz] "rats")
  414.      @result{} [foo 23 [bar baz] "rats"]
  415. (vector)
  416.      @result{} []
  417. @end group
  418. @end example
  419. @end defun
  420.  
  421. @defun make-vector integer object
  422. This function returns a new vector consisting of @var{integer} elements,
  423. each initialized to @var{object}.
  424.  
  425. @example
  426. @group
  427. (setq sleepy (make-vector 9 'Z))
  428.      @result{} [Z Z Z Z Z Z Z Z Z]
  429. @end group
  430. @end example
  431. @end defun
  432.  
  433. @defun vconcat &rest sequences
  434. @cindex copying vectors
  435. This function returns a new vector containing all the elements of the
  436. @var{sequences}.  The arguments @var{sequences} may be lists, vectors,
  437. or strings.  If no @var{sequences} are given, an empty vector is
  438. returned.
  439.  
  440. The value is a newly constructed vector that is not @code{eq} to any
  441. existing vector.
  442.  
  443. @example
  444. @group
  445. (setq a (vconcat '(A B C) '(D E F)))
  446.      @result{} [A B C D E F]
  447. (eq a (vconcat a))
  448.      @result{} nil
  449. @end group
  450. @group
  451. (vconcat)
  452.      @result{} []
  453. (vconcat [A B C] "aa" '(foo (6 7)))
  454.      @result{} [A B C 97 97 foo (6 7)]
  455. @end group
  456. @end example
  457.  
  458. When an argument is an integer (not a sequence of integers), it is
  459. converted to a string of digits making up the decimal printed
  460. representation of the integer.  This special case exists for
  461. compatibility with Mocklisp, and we don't recommend you take advantage
  462. of it.  If you want to convert an integer in this way, use @code{format}
  463. (@pxref{Formatting Strings}) or @code{int-to-string} (@pxref{String
  464. Conversion}).
  465.  
  466. For other concatenation functions, see @code{mapconcat} in @ref{Mapping
  467. Functions}, @code{concat} in @ref{Creating Strings}, and @code{append}
  468. in @ref{Building Lists}.
  469. @end defun
  470.  
  471.   The @code{append} function may be used to convert a vector into a list
  472. with the same elements (@pxref{Building Lists}):
  473.  
  474. @example
  475. @group
  476. (setq avector [1 two (quote (three)) "four" [five]])
  477.      @result{} [1 two (quote (three)) "four" [five]]
  478. (append avector nil)
  479.      @result{} (1 two (quote (three)) "four" [five])
  480. @end group
  481. @end example
  482.